CD Ware Multimedia 1995 May/cd Ware (Juegos) Epimundo.iso/DOS/C/WLIB.ZIP/WMISC.DOC

Text File | 1993-02-12 | 11.1 KB | 346 lines

Miscellaneous library documentation

October 11, 1989
February 20, 1991
May 15, 1992 (minor update)
October 20, 1992 (minor update)
January 27, 1993 (minor update)

copyright (c) 1992, 1993 by Paul Wheaton

Note that this documentation does not cover all of the features of the
provided in this library.  For that, you will have to look at the header files.

The Wheaton Libraries are shareware. Anyone may use the libraries provided
that they do not change them.  If you want to change them or if you want
phone support from me, you must pay $50. This in the hope that the hundreds
of vendors that are creating their own string libraries can go with just
one - I'm pretty tired of getting a library in that seems like it will be
pretty cool, just to find out that it uses the same identifiers as
something else and there are then link conflicts.

To make these libraries available, you need to include <Misc.h> and link
with WLIB.LIB.

      Miscellaneous
1       Type definitions
2       Constants
2.1       Type limits
2.2       Boolean
2.3       Position indicator (Left, Right and Center)
3       Functions
3.01      Abs()
3.02      Max()
3.03      Min()
3.04      InRange()
3.05      Delay()
3.06      Sound()
3.07      Beep()
3.08      Randomize()
3.09      Random()
3.10      DebugPause()
3.11      CopyArray()
3.12      CopyString()
3.13      ClearStruct()
3.14      ClearArray()
3.15      Rounding functions
3.16      ToUpper() ToLower()
3.17      PigeonHole()
3.18      SystemTick()
3.19      CRC()
4       Loop handling
4.1       Loop
4.2       For


1 Type definitions

  Using these types allow programmer control over the consistency of what
  they describe from environment to environment.  In K&R C (or pre-ANSI C),
  the definitions where that "int" could be a 32 bit integer on some
  systems and a 16 bit integer on others, whatever seemed more "natural"
  for the computer. Now, the ANSI standard supports the old K&R style but
  have added that although some computers like 32 bit values better, they
  are required to accept the use of 16 bit values.  The compiler may
  actually manipulate the 16 bit value in a 32 bit data area provided that
  the program is treated as though it's a 16 bit area.

            Number
  Type      of bits      Sign?
  -------   -------      -----
  Bool          8         No       Use only one bit for True or False
  Byte          8         No
  SByte         8         Yes
  Word         16         No
  SWord        16         Yes
  Long         32         No
  SLong        32         Yes

2 Constants

2.1 Type limits

  These limits are for the scalar types defined in section 1.  Of course,
  anything that isn't signed has a minimum of 0.  The max constants are:
  MaxByte, MaxSByte, MaxWord, MaxSWord, MaxLong and MaxSLong.  The min
  constants are:  MinSByte, MinSWord and MinSLong.

2.2 Boolean

  Of course, there's True and False.  There's also Yes, No, On and Off.

2.3 Position indicator (Left, Right and Center)

  The constants Left, Right and Center are recognized by several
  different functions as parameters.  Display and JustText are two
  that come to mind.  In the case of Display, if you pass Center in
  the X parameter, the String (that is also passed) will be placed
  such that it is centered on that row of the window.  These numbers
  may be stored as large negative values (type SWord), so be careful
  that you don't try to assign them to incompatible types.

3 Functions

3.01 Abs()

  Prototype:  [num type] Abs([num type])

  Overloaded so that you don't need a different function for every
  type.  Pass any numeric type that will hold a negative number and it
  will return the same type.

3.02 Max()

  Prototype:  [num type] Max([num type],[num type])

  Overloaded function that takes two arguments of the same type and
  returns the larger value as the same type.

3.03 Min()

  Prototype:  [num type] Min([num type],[num type])

  Overloaded function that takes two arguments of the same type and
  returns the smaller value as the same type.

3.04 InRange()

  Prototype:  Bool InRange([num type] Val, [num type] Low, [num type] High)

  Overloaded function that takes three arguments of the same type and
  returns True if the first number is in the range of the other two,
  inclusively.

3.05 Delay()

  Prototype:  void Delay(long MilliSecs)

  Delay this process for the number of milliseconds passed.  A value
  passed of 1000 means delay for one second.  Note that on
  multi-tasking systems, the operating system will turn the CPU time
  over to something else for this period of time.

3.06 Sound()

  Prototype:  void Sound(float Pitch, int MilliSecs)

  For values to plug into Pitch, see page 147 of "The Peter Norton
  Programmer's Guide to the IBM PC".  If you don't want to bother to
  look there and don't know what "pitch" or frequency is, then let's
  just say that higher numbers play higher notes.  MilliSecs is how
  long the sound lasts.  This function won't come back until it's done
  making its noise.

3.07 Beep()

  Prototype:  void Beep(int Num=1)

  For those that are not familiar with default parameters, let me
  point out that you may call this function without any paramters
  (Beep();) and there will be one beep.  You also have the option of
  calling it with one parameter and specify the number of beeps that
  you want.  "Beep(4);" will play 4 beeps.

3.08 Randomize()

  Prototype:  void Randomize()

  Initializes the random number generator.

3.09 Random()

  Prototype:  int Random(int Max)

  Returns a random integer in the range of 0..Max-1.

3.10 DebugPause()

  Prototype:  void DebugPause(ConstantStringMessage)

  Displays the string onto the screen rather sloppily and pauses for a
  second or two.  Since this function uses a macro, the string
  parameter MUST be a string constant.

    DebugPause("xxx entering loop");  // valid call
    DebugPause(SomeString_AnyStringType);   // invalid call

3.11 CopyArray()

  Prototype:  void* CopyArray(DestArray,SourceArray)

  The functions CopyArray, CopyString, ClearStruct and ClearArray all
  expect straight parameters without any extra pointers or
  referencing.  Since these functions are macros, the first (or only)
  parameter must be something that sizeof will work on effectively.

  If SourceArray is smaller than DestArray, a bunch of garbage will be
  in the end of DestArray.  If SourceArray is bigger than DestArray,
  only a subset will be copied.  Note that this is just a bitwise copy
  and does not care what the types of either array are.

    static int A1[5]={1,2,3,4,5};
    int A2[3];
    CopyArray(A2,A1);  //  A2 now contains the first 3 elements of A1
    int *A3=A2;
    CopyArray(A3,A1);  //  unpredictable results!!!
      // sizeof a pointer probably isn't what is desired

3.12 CopyString()

  Prototype: void CopyString(Dest,Source)

  Just like CopyArray, cept it will stop if it finds a null character
  and make sure that there's a null character copied over.  Note that
  this is for strings of type char* only!

3.13 ClearStruct()

  Prototype: void ClearStruct(S)

  Fills the struct with zeros.

    struct
      {
        long A,B,C,D,E,F;
      } S;
    ClearStruct(S);

3.14 ClearArray()

  Prototype:  ClearArray(A)

  Fills the array with zeros.

    float F[20];
    ClearArray(F);

3.15 Rounding functions

  Prototypes:  long Round(double Val)
               long RoundUp(double Val)
               long RoundDown(double Val)
               long RoundOut(double Val)
               long RoundIn(double Val)

  Initial value     .2    .7   -.2   -.7

  Round()            0     1     0    -1
  RoundUp()          1     1     0     0
  RoundDown()        0     0    -1    -1
  RoundOut()         1     1    -1    -1
  RoundIn()          0     0     0     0

3.16      ToUpper() ToLower()

  Prototypes:  char ToUpper(char C)
               char ToLower(char C)

  If a lower case char is passed to ToUpper() it will be converted to
  an upper case char.  Any other characters passed in will be
  unchanged.  ToLower() works the same way except that upper case
  chars are converted to lower case.

3.17      PigeonHole()

  Prototype:  void PigeonHole(long TotQuan, int ArrayLen, int A[]);

  This function will take TotQuan and spread it as evenly as possible
  over the array A.  Example:

    If you pass 13 in for TotQuan and 5 in for ArrayLen, A will have
    the values 3, 2, 3, 2, 3.

3.18      SystemTick()

  Prototype:  Long SystemTick()

  This function will return the current system tick.  On a PC
  compatible machine (running any OS) you will get about 18 ticks per
  second.

3.19      CRC()

  Prototypes:  Word CRC(void* P,Long Size)
               Word CRC(const Char* S)

  The functions will return a 16 bit CRC (commonly known as a CRC16)
  based on the data given.  For the first function, pass a pointer to
  anywhere in memory and then the number of bytes you want to be
  included in the CRC calculation.  The second function performs a CRC
  on a null terminated string (does not include the null terminator).

  A CRC is like an advanced checksum.  It is used for integrity
  checking and encryption.  For more info, see the book
  "C Programmer's Guide to Serial Communications" pp 533 - 550.

4 Loop handling

  These loop handling macros are enhanced forms of existing loop
  handling constructs.

4.1 Loop

  Sets up an infinite loop.  Generally, stopping the loop is with a
  "return".

    // program to keep on beeping until computer is reset
    Loop
      {
        Beep();
      }

4.2 For

  This loop construct replaces the most common use of "for" in C
  programming:  A variable starts at zero, is incremented with each
  iteration and stops just before reaching the stop value. This macro
  is a simpler, more readable, less error prone loop construct.
  Replace

    int I;
    for(I=0;I<15;I++)
        Beep();

  with

    int I;
    For(I,15)
        Beep();

  Note that in the "for" version, "I" is referenced three times, there
  are two semicolon delimiters, an assignment operator with an
  initialization value, a comparison operator, an increment operator,
  a stop value and is 17 characters long.  In the "For" version there
  is one comma delimiter, one reference to "I", the stop value and is
  9 characters long.  Whenever there's a bug in a piece of code that
  has a "for" loop like the one above, the first thing I check is how
  many iterations there were.  What would go through my mind in the
  above example is:  "All three parts have an 'I', not a 'l', 'i' or '1'.
  The comparison operator is '<' not '<=' or '>'.  'I' is initialized
  to '0' not 'O' or '1'.  'I' is incremented properly.  Semicolons
  were used, not commas or colons."  Now that I've used the "For"
  macro for a while, I'm used to seeing the above example and thinking
  "It did iterate 15 times."  There's only two things to check:  The
  proper variable was used and the right stop value was used.